Workshop 2 - RMarkdown

The aim

We want to present the results and the visuals in ways that are easier to share with people. We will knit the RMarkdown file into a PDF or a the webpage, so people can have all the info in one place together (with the code if it is a webpage).

Structure

As we have mentioned in the last workshop (or not), we suggest you to have some folders to keep everything tidy.

data: your data
scripts: for the scripts, including .R and .Rmd files
docs: for the output
images (optional): for the images

Knit into html

We will create a webpage using RMarkdown and publish it as a GitHub page.

example 1 - Visual models

example 2 - Heating rate

Details

Let’s take a closer look what we can have in a webpage.

2. Table

3. Tabs

4. Code button

Essentials Files

There are two files you need to have to publish a webpage:

index.html: default homepage
_site.yml: essential if you want to have more than one page on your site. It provides the global YAML header for the site.

Exercise 1: Copy the Website repo from Bug of the week to your own GitHub.

Note: You would like to save your output html files in the docs folder. To do so, you will need to change the directory in the yaml header like the following code:

knit: (function(inputFile, encoding) {
  rmarkdown::render(inputFile, encoding = encoding, output_dir = "../docs") })

html

Content page

You can create RMarkdown files and set the output into html format.
Where to set it?
You will set the output formate and appearance in the yaml header of your RMarkdown file.
What and where is the yaml header?
In (very) short, it controls the overall appearance of the page and it is on the top of the file like this:

---
title: "Workshop 2: RMarkdown"
author: "Amanda Franklin, Laura Ospina, Lu-Yi Wang"
date: "4/25/2022"
output: html_document
knit: (function(inputFile, encoding) {
  rmarkdown::render(inputFile, encoding = encoding, output_dir = "../docs") })
---

See here and here for more details about yaml.

Exercise 2: Create 2 RMarkdown pages. Knit them into html and save them in the docs folder. Try to apply the syntax Amanda just showed you.

Index page

Remember that we need a index.html file for the homepage? You can either assgin one of the pages you create as the homepage by changing the name of the corresponding .Rmd file to index and knit it again, or you can create a new .Rmd file and call it index.

To link to other page, you an use the following code

[text](html file name/http address)

# For example, if in the same folder 
# [Workshop 1: Github](workshopGithub.html) 
# Or [Bug of the week](https://github.com/bugoftheweek)

Exercise 3: Make your index.html file and try to link it to the pages you just made.

yml

We have created two separate pages. How do we combine them into one site?
To do this, we need the _site.yml file (need to specifically called _site.yml).

Create a text file

Note: You need to place the _site.yml file in the same folder as other .Rmd files

Change the file type to .yml by adding “.yml” at the end of the file.
**Inside the _site.yml file** Whatever you put here will overwrite the ymal header in the separate .Rmd files. In side the file, we will specify some things including the headers, the table, the theme, and the output directory.

Note: you need to set the output directory to the same folder (docs) as other html to be able to combine them into one site

name: "Lab Workshop"
navbar:
  title: ""
  subtitle: Supplementary Information
  Date: "April 25th 2022"
  left: # left side of the header
  - text: "Introduction"
    href: index.html
  - text: "Workshop 1: Github"
    href: workshopGithub.html
  - text: "Workshop 2: RMarkdown"
    href: workshopRMarkdown.html
  right: # right side of the header
  - icon: fa-github # icon of GitHub
    text: Bug of the week
    href: https://github.com/bugoftheweek # You can also have a http address 
      
output:
  html_document:
    toc: true # table of content true
    toc_float: # have a table of content at the left side
      collapsed: true #default true, only show up tp level 2 unless click to expand
      smooth_scroll: true #animated the page to the clicked item
    depth: 6  # up to three depths of headings (specified by #, ## and ###)
    number_sections: false  #  number sections at each table header
    theme: flatly # theme for fonts and colours
    highlight: tango # different theme for the appearance of the code
output_dir: "../docs"

Exercise 4: Make some edits (e.g. headers) in your _site.yml file!

Knit into a PDF

To knit into a PDF, you don’t need the .yml file. All you need is to do is to change the output format into “pdf_document”
If you choose the output format to PDF upon creating the RMarkdown, it will automatically assign the output format to PDF. But you need to change the output directory to the docs folder.

However, there are some difference in syntax between the two formats and functions are available in html but not in PDF, e.g. Tabs, code buttons. So they are not completely compatible.

output: pdf_document

Exercise 4: Try to make one RMardown file and knit it into a PDF.

Workshop 2: RMarkdown

Amanda Franklin, Laura Ospina, Lu-Yi Wang

4/25/2022